home *** CD-ROM | disk | FTP | other *** search
/ IRIX 6.2 Development Libraries / SGI IRIX 6.2 Development Libraries.iso / dist / complib.idb / usr / share / catman / p_man / cat3 / complib / cggsvd.z / cggsvd
Text File  |  1996-03-14  |  9KB  |  265 lines
  1.  
  2.  
  3.  
  4. CCCCGGGGGGGGSSSSVVVVDDDD((((3333FFFF))))                                                          CCCCGGGGGGGGSSSSVVVVDDDD((((3333FFFF))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      CGGSVD - compute the generalized singular value decomposition (GSVD) of
  10.      an M-by-N complex matrix A and P-by-N complex matrix B
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      SUBROUTINE CGGSVD( JOBU, JOBV, JOBQ, M, N, P, K, L, A, LDA, B, LDB,
  14.                         ALPHA, BETA, U, LDU, V, LDV, Q, LDQ, WORK, RWORK,
  15.                         IWORK, INFO )
  16.  
  17.          CHARACTER      JOBQ, JOBU, JOBV
  18.  
  19.          INTEGER        INFO, K, L, LDA, LDB, LDQ, LDU, LDV, M, N, P
  20.  
  21.          INTEGER        IWORK( * )
  22.  
  23.          REAL           ALPHA( * ), BETA( * ), RWORK( * )
  24.  
  25.          COMPLEX        A( LDA, * ), B( LDB, * ), Q( LDQ, * ), U( LDU, * ), V(
  26.                         LDV, * ), WORK( * )
  27.  
  28. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  29.      CGGSVD computes the generalized singular value decomposition (GSVD) of an
  30.      M-by-N complex matrix A and P-by-N complex matrix B:
  31.  
  32.            U'*A*Q = D1*( 0 R ),    V'*B*Q = D2*( 0 R )
  33.  
  34.      where U, V and Q are unitary matrices, and Z' means the conjugate
  35.      transpose of Z.  Let K+L = the effective numerical rank of the matrix
  36.      (A',B')', then R is a (K+L)-by-(K+L) nonsingular upper triangular matrix,
  37.      D1 and D2 are M-by-(K+L) and P-by-(K+L) "diagonal" matrices and of the
  38.      following structures, respectively:
  39.  
  40.      If M-K-L >= 0,
  41.  
  42.                          K  L
  43.             D1 =     K ( I  0 )
  44.                      L ( 0  C )
  45.                  M-K-L ( 0  0 )
  46.  
  47.                        K  L
  48.             D2 =   L ( 0  S )
  49.                  P-L ( 0  0 )
  50.  
  51.                      N-K-L  K    L
  52.        ( 0 R ) = K (  0   R11  R12 )
  53.                  L (  0    0   R22 )
  54.      where
  55.  
  56.        C = diag( ALPHA(K+1), ... , ALPHA(K+L) ),
  57.        S = diag( BETA(K+1),  ... , BETA(K+L) ),
  58.        C**2 + S**2 = I.
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. CCCCGGGGGGGGSSSSVVVVDDDD((((3333FFFF))))                                                          CCCCGGGGGGGGSSSSVVVVDDDD((((3333FFFF))))
  71.  
  72.  
  73.  
  74.        R is stored in A(1:K+L,N-K-L+1:N) on exit.
  75.  
  76.      If M-K-L < 0,
  77.  
  78.                        K M-K K+L-M
  79.             D1 =   K ( I  0    0   )
  80.                  M-K ( 0  C    0   )
  81.  
  82.                          K M-K K+L-M
  83.             D2 =   M-K ( 0  S    0  )
  84.                  K+L-M ( 0  0    I  )
  85.                    P-L ( 0  0    0  )
  86.  
  87.                         N-K-L  K   M-K  K+L-M
  88.        ( 0 R ) =     K ( 0    R11  R12  R13  )
  89.                    M-K ( 0     0   R22  R23  )
  90.                  K+L-M ( 0     0    0   R33  )
  91.  
  92.      where
  93.  
  94.        C = diag( ALPHA(K+1), ... , ALPHA(M) ),
  95.        S = diag( BETA(K+1),  ... , BETA(M) ),
  96.        C**2 + S**2 = I.
  97.  
  98.        (R11 R12 R13 ) is stored in A(1:M, N-K-L+1:N), and R33 is stored
  99.        ( 0  R22 R23 )
  100.        in B(M-K+1:L,N+M-K-L+1:N) on exit.
  101.  
  102.      The routine computes C, S, R, and optionally the unitary
  103.      transformation matrices U, V and Q.
  104.  
  105.      In particular, if B is an N-by-N nonsingular matrix, then the GSVD of A
  106.      and B implicitly gives the SVD of A*inv(B):
  107.                           A*inv(B) = U*(D1*inv(D2))*V'.
  108.      If ( A',B')' has orthnormal columns, then the GSVD of A and B is also
  109.      equal to the CS decomposition of A and B. Furthermore, the GSVD can be
  110.      used to derive the solution of the eigenvalue problem:
  111.                           A'*A x = lambda* B'*B x.
  112.      In some literature, the GSVD of A and B is presented in the form
  113.                       U'*A*X = ( 0 D1 ),   V'*B*X = ( 0 D2 )
  114.      where U and V are orthogonal and X is nonsingular, and D1 and D2 are
  115.      ``diagonal''.  The former GSVD form can be converted to the latter form
  116.      by taking the nonsingular matrix X as
  117.  
  118.                            X = Q*(  I   0    )
  119.                                  (  0 inv(R) )
  120.  
  121.  
  122. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  123.      JOBU    (input) CHARACTER*1
  124.              = 'U':  Unitary matrix U is computed;
  125.              = 'N':  U is not computed.
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. CCCCGGGGGGGGSSSSVVVVDDDD((((3333FFFF))))                                                          CCCCGGGGGGGGSSSSVVVVDDDD((((3333FFFF))))
  137.  
  138.  
  139.  
  140.      JOBV    (input) CHARACTER*1
  141.              = 'V':  Unitary matrix V is computed;
  142.              = 'N':  V is not computed.
  143.  
  144.      JOBQ    (input) CHARACTER*1
  145.              = 'Q':  Unitary matrix Q is computed;
  146.              = 'N':  Q is not computed.
  147.  
  148.      M       (input) INTEGER
  149.              The number of rows of the matrix A.  M >= 0.
  150.  
  151.      N       (input) INTEGER
  152.              The number of columns of the matrices A and B.  N >= 0.
  153.  
  154.      P       (input) INTEGER
  155.              The number of rows of the matrix B.  P >= 0.
  156.  
  157.      K       (output) INTEGER
  158.              L       (output) INTEGER On exit, K and L specify the dimension
  159.              of the subblocks described in Purpose.  K + L = effective
  160.              numerical rank of (A',B')'.
  161.  
  162.      A       (input/output) COMPLEX array, dimension (LDA,N)
  163.              On entry, the M-by-N matrix A.  On exit, A contains the
  164.              triangular matrix R, or part of R.  See Purpose for details.
  165.  
  166.      LDA     (input) INTEGER
  167.              The leading dimension of the array A. LDA >= max(1,M).
  168.  
  169.      B       (input/output) COMPLEX array, dimension (LDB,N)
  170.              On entry, the P-by-N matrix B.  On exit, B contains part of the
  171.              triangular matrix R if M-K-L < 0.  See Purpose for details.
  172.  
  173.      LDB     (input) INTEGER
  174.              The leading dimension of the array B. LDB >= max(1,P).
  175.  
  176.      ALPHA   (output) REAL array, dimension (N)
  177.              BETA    (output) REAL array, dimension (N) On exit, ALPHA and
  178.              BETA contain the generalized singular value pairs of A and B;
  179.              ALPHA(1:K) = 1,
  180.              BETA(1:K)  = 0, and if M-K-L >= 0, ALPHA(K+1:K+L) = C,
  181.              BETA(K+1:K+L)  = S, or if M-K-L < 0, ALPHA(K+1:M)= C,
  182.              ALPHA(M+1:K+L)= 0
  183.              BETA(K+1:M) = S, BETA(M+1:K+L) = 1 and ALPHA(K+L+1:N) = 0
  184.              BETA(K+L+1:N)  = 0
  185.  
  186.      U       (output) COMPLEX array, dimension (LDU,M)
  187.              If JOBU = 'U', U contains the M-by-M unitary matrix U.  If JOBU =
  188.              'N', U is not referenced.
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. CCCCGGGGGGGGSSSSVVVVDDDD((((3333FFFF))))                                                          CCCCGGGGGGGGSSSSVVVVDDDD((((3333FFFF))))
  203.  
  204.  
  205.  
  206.      LDU     (input) INTEGER
  207.              The leading dimension of the array U. LDU >= max(1,M) if JOBU =
  208.              'U'; LDU >= 1 otherwise.
  209.  
  210.      V       (output) COMPLEX array, dimension (LDV,P)
  211.              If JOBV = 'V', V contains the P-by-P unitary matrix V.  If JOBV =
  212.              'N', V is not referenced.
  213.  
  214.      LDV     (input) INTEGER
  215.              The leading dimension of the array V. LDV >= max(1,P) if JOBV =
  216.              'V'; LDV >= 1 otherwise.
  217.  
  218.      Q       (output) COMPLEX array, dimension (LDQ,N)
  219.              If JOBQ = 'Q', Q contains the N-by-N unitary matrix Q.  If JOBQ =
  220.              'N', Q is not referenced.
  221.  
  222.      LDQ     (input) INTEGER
  223.              The leading dimension of the array Q. LDQ >= max(1,N) if JOBQ =
  224.              'Q'; LDQ >= 1 otherwise.
  225.  
  226.      WORK    (workspace) COMPLEX array, dimension (max(3*N,M,P)+N)
  227.  
  228.      RWORK   (workspace) REAL array, dimension (2*N)
  229.  
  230.      IWORK   (workspace) INTEGER array, dimension (N)
  231.  
  232.      INFO    (output)INTEGER
  233.              = 0:  successful exit.
  234.              < 0:  if INFO = -i, the i-th argument had an illegal value.
  235.              > 0:  if INFO = 1, the Jacobi-type procedure failed to converge.
  236.              For further details, see subroutine CTGSJA.
  237.  
  238. PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS
  239.      TOLA    REAL
  240.              TOLB    REAL TOLA and TOLB are the thresholds to determine the
  241.              effective rank of (A',B')'. Generally, they are set to TOLA =
  242.              MAX(M,N)*norm(A)*MACHEPS, TOLB = MAX(P,N)*norm(B)*MACHEPS.  The
  243.              size of TOLA and TOLB may affect the size of backward errors of
  244.              the decomposition.
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.